/**
 * \addtogroup Orientation Orientation API
 * @{  
 *  This file specifies the Samsung Orientation API for Windows Mobile devices.
 *
 * The Orientation API is a service-level API that provides a centralized orientation service 
 * for all applications. This API enables applications to register handlers associated 
 * with phone movements. 
 * This API is implemented by a centralized polling mechanism for effective CPU utilization.
 *
 * Copyright &copy; 2009 Samsung Electronics
 *   
 * File: smiOrientation.h
 */
#ifndef _SMI_ORIENTATION_H
#define _SMI_ORIENTATION_H

#include <smiSDK.h>
#include <smiAccelerometer.h>

typedef enum
/**
* Indicates orientation of the main display of the device.
*/
{
	SMI_ORIENTATION_FACE_UP,
	SMI_ORIENTATION_FACE_DOWN,   	
	SMI_ORIENTATION_LANDSCAPE,          
	SMI_ORIENTATION_REVERSE_LANDSCAPE,
	SMI_ORIENTATION_PORTRAIT,
	SMI_ORIENTATION_REVERSE_PORTRAIT,
	SMI_ORIENTATION_UNDEFINED
} SmiOrientation;



/** 
*  Function signature for orientation event handlers. 
*/
typedef void (*SmiOrientationEventHandler)(SmiOrientation);

/**
 *  Gets the current orientation state. 
 *
 *  @param	state    [out]		A pointer to the orientation state.  
 *
 *  @return                     
 *                              SMI_SUCCESS on success
 *  \n                          SMI_ERROR_INVALID_PARAMETER if the input parameter is NULL
 *  \n                          SMI_ERROR_DEVICE_NOT_FOUND if the device is not present or supported
 *  \n                          SMI_ERROR_CANNOT_ACTIVATE_SERVER if the sensor server cannot be started
 *  \n                          SMI_ERROR_UNKNOWN for all other failures
 */
 SMI_API SMI_RESULT SmiOrientationGetState(SmiOrientation * state);
 
 /**
 *  Registers a handler to be called when the device orientation changes to the orientation 
 *  specified in \a state.
 *
 *  Only one handler per process can be registered for each device orientation.  
 *  Subsequent registrations replace the previous handler associated with that device orientation.
 *
 *  @param	state      [in]		The orientation state.  
 *  @param	handler    [in]		A callback function.  
 *
 *  @return                     
 *                              SMI_SUCCESS on success
 *  \n                          SMI_ERROR_INVALID_PARAMETER if the input parameter is NULL or invalid
 *  \n                          SMI_ERROR_DEVICE_NOT_FOUND if the device is not present or supported     
 *  \n                          SMI_ERROR_CANNOT_ACTIVATE_SERVER if the sensor server cannot be started
 */
 SMI_API SMI_RESULT SmiOrientationRegisterOnStateHandler( SmiOrientation state ,
	 SmiOrientationEventHandler handler);

/**
 *  Unregisters the handler associated with the given state by a previous call to the 
 *  SmiOrientationRegisterOnStateHandler() function. It does not affect a handler registered by the 
 *  SmiOrientationRegisterOnChangeHandler() function. 
 *
 *  @param	state    [in]		The orientation state.  
 *
 *  @return                     
 *                              SMI_SUCCESS on success
 *  \n                          SMI_ERROR_INVALID_PARAMETER if the input parameter is invalid
 *  \n                          SMI_ERROR_DEVICE_NOT_FOUND if the device is not present or supported 
 *  \n                          SMI_ERROR_CANNOT_ACTIVATE_SERVER if the sensor server cannot be started
 */
 SMI_API SMI_RESULT SmiOrientationUnregisterOnStateHandler(SmiOrientation state);

 /**
 *  Registers a handler to be called whenever the orientation is changed. The handler is called even when the
 *  device enters the SMI_ORIENTATION_UNDEFINED state.
 * 
 *  Only one OnState handler per process can be registered.  
 *  Subsequent registrations replace the previous OnState handler.
 *
 *  @param	handler    [in]		A callback function.  
 *
 *  @return                     
 *                              SMI_SUCCESS on success
 *  \n                          SMI_ERROR_INVALID_PARAMETER if the input parameter is NULL
 *  \n                          SMI_ERROR_DEVICE_NOT_FOUND if the device is not present or supported
 *  \n                          SMI_ERROR_CANNOT_ACTIVATE_SERVER if the sensor server cannot be started
 */
 SMI_API SMI_RESULT SmiOrientationRegisterOnChangeHandler(
	 SmiOrientationEventHandler handler);

/**
 *  Unregisters the handler associated by a previous call to the 
 *  SmiOrientationRegisterOnChangeHandler() function. It does not affect handlers registered by the 
 *  SmiOrientationRegisterOnStateHandler() function. 
 *
 *  @return                     
 *                              SMI_SUCCESS on success
 *  \n                          SMI_ERROR_DEVICE_NOT_FOUND if the device is not present or supported
 *  \n                          SMI_ERROR_CANNOT_ACTIVATE_SERVER if the sensor server cannot be started
 */
 SMI_API SMI_RESULT SmiOrientationUnregisterOnChangeHandler();

#endif
 /* @} */